Examples: read the token from CONVERTAPI_TOKEN and find the sample files from any folder - #85

Stacked on #82. Please merge #82 first; until then this pull request also shows its one commit (3d70c44), which changes the thumbnail example's comment and parameters.

Problem

None of the examples ran as written:

• Sample-file paths. The examples reached Examples/TestFiles through paths relative to the working directory, written two ways: 6 uses climbed three levels (@"..\..\..\TestFiles\...") and 9 climbed four (@"..\..\..\..\TestFiles\..."). From the build output folder bin\Debug\net10.0, which is where Visual Studio starts a program, only the four-level form reaches Examples\TestFiles. From the repository or project folder, where dotnet run starts it, neither does. On macOS and Linux the backslash paths do not resolve at all. UploadOnceReuseTwice and Workflow climbed four levels from AppContext.BaseDirectory, which breaks with any other output layout, for example a runtime-specific bin/Debug/net10.0/osx-arm64. SplitPDF read files/sample.pdf relative to the working directory, so dotnet run --project Examples/SplitPDF from the repository root could not find it.
• Token. Every example hard-coded new ConvertApi("api_token") (SplitPDF "api-token"), so each one had to be edited before it could run.

Change

• Each example's .csproj copies the sample files it uses to TestFiles/ next to the program:

  <None Include="..\TestFiles\test.pdf" Link="TestFiles\test.pdf" CopyToOutputDirectory="PreserveNewest" />

  and Program.cs reads them from there:

  // Sample file from Examples/TestFiles, copied next to the program when it builds
  var pdfFile = Path.Combine(AppContext.BaseDirectory, "TestFiles", "test.pdf");

  That works from any working directory: dotnet run --project from the repository root, dotnet run in the project folder, Visual Studio and Rider (output folder), on Windows, macOS and Linux. SplitPDF does the same with its own files/sample.pdf, which its .csproj already copied.

• The token comes from the CONVERTAPI_TOKEN environment variable, and the comment that says where to get a token stays:

  //Get your API Token at https://www.convertapi.com/a/authentication
  var convertApi = new ConvertApi(Environment.GetEnvironmentVariable("CONVERTAPI_TOKEN"));

  CONVERTAPI_TOKEN, not the API_TOKEN that the Go, Java, Node, Python and Ruby examples read, because the README quick start in README: code that runs as copied, a quick start and C# tasks; NuGet packs the same README #83 and the C# pages on convertapi.com set CONVERTAPI_TOKEN: a reader who sets it once can run the README snippets and these examples. If the variable is not set, the SDK stops with ArgumentNullException for apiToken.

• New Examples/README.md: how to set the variable and run an example. The run steps in Examples/UploadOnceReuseTwice/README.md no longer say to edit the token into Program.cs.

Only the examples change, not the library, so there is no CHANGELOG entry.

Verification

Run on macOS (arm64) with .NET SDK 10.0.401 against the production API on 2026-11-09, with CONVERTAPI_TOKEN set and nothing edited. $TMPDIR is the local temp folder.

• Build: dotnet build ConvertApi.sln and the CI build dotnet build ConvertApi.sln -c Release -p:ContinuousIntegrationBuild=true both succeed with 0 errors. The 3 warnings are in lines this pull request does not change (CS8603 and CS8625 in ConverterCatalogDemo, CS0618 in GetConverterInfoDemo). Each example's bin/<Configuration>/net10.0/TestFiles holds exactly the files it uses.
• Runs: all 21 examples ran with dotnet run --project Examples/<Name> < /dev/null from the repository root and exited with code 0 (ExceptionHandling prints its intended 400 error). CreatePdfThumbnail also ran from the project folder, from bin/Debug/net10.0 and from a folder outside the repository. Its test.jpg is 231x300 px, 8,858 bytes, as in PDF thumbnail example: fix the comment, keep the thumbnail inside 300x300 #82.
• WatermarkPdf crashed before the second commit, after it had saved its result: Unhandled exception. System.ComponentModel.Win32Exception (13): An error occurred trying to start process '$TMPDIR/watermarked-....pdf' with working directory '<repository>'. Permission denied. Process.Start(path) uses UseShellExecute = false on .NET Core and later, so it fails on Windows too. The second commit removes that line.

CreatePdfThumbnail, a DOCX example and an example with two sample files:

$ dotnet run --project Examples/CreatePdfThumbnail < /dev/null
The thumbnail saved to $TMPDIR/test.jpg
$ cd Examples/CreatePdfThumbnail && dotnet run < /dev/null
The thumbnail saved to $TMPDIR/test.jpg
$ cd Examples/CreatePdfThumbnail/bin/Debug/net10.0 && ./CreatePdfThumbnail < /dev/null   # where Visual Studio starts it
The thumbnail saved to $TMPDIR/test.jpg
$ cd <a folder outside the repository> && dotnet run --project <repository>/Examples/CreatePdfThumbnail < /dev/null
The thumbnail saved to $TMPDIR/test.jpg

$ dotnet run --project Examples/ConvertWordToPdfAndPng < /dev/null
The PDF saved to $TMPDIR/test.pdf
The PNG saved to $TMPDIR/test.png
The PNG saved to $TMPDIR/test-2.png

$ dotnet run --project Examples/MergeWordDocsToPdf < /dev/null
The example shows how to merge Word and Powerpoint documents to one PDF by converting them to PDFs and then merging. Please wait...
Word sent for conversion...
PowerPoint sent for conversion...
The PDF saved to $TMPDIR/test-merged-cd0b55f1-8088-4960-9da7-d268f92308dd.pdf
Elapsed 00:00:01.9120645

$ dotnet run --project Examples/ConvertPdfToPdfA < /dev/null
The converted PDF/A saved to $TMPDIR/result-pdfa-7c675f02-d380-4027-8794-a798d9acb74d.pdf
$ dotnet run --project Examples/ConvertPdfToDocx < /dev/null
The converted DOCX saved to $TMPDIR/result-f1565735-7bcf-463c-82be-3c62c834e485.docx
$ dotnet run --project Examples/ConvertPdfToPptx < /dev/null
The converted PPTX saved to $TMPDIR/result-966d9447-4111-4461-80aa-a74da9e57aff.pptx
$ dotnet run --project Examples/ConvertPdfToXlsx < /dev/null
The converted XLSX saved to $TMPDIR/result-0374e9ac-3208-48dc-a478-ba6090ad9c5c.xlsx
$ dotnet run --project Examples/DeleteFiles < /dev/null
Converting DOCX to PDF...
Saved to: $TMPDIR/delete-files-demo.pdf
Deleted 2 file(s) from server.
$ dotnet run --project Examples/ExceptionHandling < /dev/null
Status Code: BadRequest
Response: {"Code":4000,"Message":"Parameter validation error.","InvalidParameters":{"File":["File must be a file with one of the following extensions: .pdf."]}}
$ dotnet run --project Examples/HandleRetry < /dev/null
Saved to $TMPDIR/result-977eb91e-a891-4273-a281-6077f3c4de44.pptx
$ dotnet run --project Examples/SplitAndMergePdf < /dev/null
The PDF saved to $TMPDIR/test-merged-88c02536-c5ee-4eb0-bea8-53eab0d2ef0e.pdf
$ dotnet run --project Examples/UploadOnceReuseTwice < /dev/null
The PDF saved to $TMPDIR/test.pdf
The PNG saved to $TMPDIR/test.png
The PNG saved to $TMPDIR/test-2.png
Done. Press Enter to exit.
$ dotnet run --project Examples/WatermarkPdf < /dev/null
The example shows how to watermark PDF with text and put overlay PDF
PDF sent for text watermarking...
PDF sent for overlay watermarking...
The PDF saved to $TMPDIR/watermarked-69f975ee-3f20-4782-827c-2929a76f039d.pdf
Elapsed 00:00:04.3813531
$ dotnet run --project Examples/Workflow < /dev/null
Converting PDF to JPG and compressing result files with ZIP
Conversions done. Cost: 1. Total files created: 6
Conversions done. Cost: 1. Total files created: 1
File saved to $TMPDIR/test.zip
$ dotnet run --project Examples/SplitPDF < /dev/null
All splits complete!
$ dotnet run --project Examples/ConvertRemoteFile < /dev/null
Converting online PowerPoint file https://cdn.convertapi.com/public/files/demo.pptx to PDF...
The PDF saved to $TMPDIR/demo.pdf
$ dotnet run --project Examples/ConvertUrlToPdf < /dev/null
Converting web page https://en.wikipedia.org/wiki/Data_conversion to PDF...
The web page PDF saved to $TMPDIR/web-example.pdf
$ dotnet run --project Examples/FromStreamToStream < /dev/null
%PDF-1.4
[... the PDF bytes, about 22 KB, cut here ...]
%%EOF
End of file stream.
$ dotnet run --project Examples/RetrieveUserInformation < /dev/null   # account fields masked here
Secret=***
ApiKey=***
Active=True
FullName=***
Email=***
ConversionsTotal=***
ConversionsConsumed=***
$ dotnet run --project Examples/GetConverterInfoDemo < /dev/null   # only the converter, title and failure lines
Converter docx -> pdf
Title           : DOCX to PDF API
Converter pdf -> pptx
Title           : PDF to PPTX API
Converter pdf -> merge
Title           : Merge PDF API
Converter any -> pdf
Failed to get converter info for any->pdf: Converter path '/convert/any/to/pdf' not found in OpenAPI document.
$ dotnet run --project Examples/ConverterCatalogDemo < /dev/null   # first and last lines
=== ConvertAPI Converter Catalog Demo ===
Base URI: https://v2.convertapi.com

Loading catalog (OpenAPI fetch + parse)...
Loaded.

--- GetAllConverters() ---
Total converters: 328
First 10 converters:
[...]
--- Reload() ---
Reloaded. Converters count now: 328

Demo finished.

Not changed here

• ConverterCatalogDemo sets ConvertApi.ApiBaseUri to the staging API (https://stag-v2.convertapi.com) right after it prints the production address, so the public example reads the staging catalog.
• GetConverterInfoDemo asks for any -> pdf, which is not in the API spec (Converter path '/convert/any/to/pdf' not found in OpenAPI document.), and calls the obsolete GetConverterInfo (CS0618).
• ConvertUrlToPdf (web -> pdf), WatermarkPdf (pdf -> watermark, pdf -> watermark-overlay) and Workflow (jpg -> zip) still convert on production, but none of those paths is in the current spec (https://v2.convertapi.com/info/openapi, 332 paths), which lists html -> pdf with Url, pdf -> text-watermark, pdf -> pdf-watermark and file -> zip.
• SplitPDF saves its 19 result files to output/ in the current folder, which is the repository root when it runs as dotnet run --project Examples/SplitPDF, and .gitignore does not cover it. The other examples save to the temp folder.
• RetrieveUserInformation prints the account's Secret and ApiKey to the console.

🤖 Generated with Claude Code